Alias

CscCredentialsList

Description

Provides the list of signature credentials (i.e., signing identities) of a user.

Request

To obtain a user's list of signing identities, the client application must send the following request to the TRIDENT using TLS.

POST /trustedx-resources/csc/v2/credentials/list

Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be /csc/v2/. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is /csc/v2 instead of /trustedx-resources/csc/v2. To determine if this is the case in your situation, check the "oauth2" property of the JSON object provided by the Obtain information on the CSC signature service operation.

Content-Type Header

Content-Type: application/json

Request Parameters

Name	Type	Usage	Description
`userID`	String	Conditionally required	Identifier of the user whose signature credentials list is to be obtained. This parameter can only be used (and must be used in this case) when the access token demonstrating the authorization is a bearer OAuth 2.0 token obtained in a Client Credentials Grant authorization flow, I.e., when the access token is not for an authorization granted by a user in particular.
`credentialInfo`	Boolean	Optional	Request to return the main information included in the public key certificate, the public key certificate itself, or the certificate chain associated with the credentials. The default value is `false`, so if the parameter is omitted, the information will not be returned.
`certificates`	String	Conditionally optional	Specifies which certificates from the certificate chain shall be returned in `cert/certificates.` Only the following values are allowed: `"none"`: No certificate shall be returned. `"single"`: Only the end entity certificate shall be returned. `"chain"`: The full certificate chain shall be returned. The `"single"` value is the default, so if the parameter is omitted, the method will only return the user's certificates. This parameter may be specified only if the parameter `credentialInfo` is `true`. If the parameter `credentialInfo` is not `true` and this parameter is specified, its value will be ignored.
`certInfo`	Boolean	Conditionally optional	Request to return various parameters containing information from the user certificates. This is useful in case the signature application wants to retrieve some details of the certificates without having to decode them first. The default value is `false`, so the information will not be returned if the parameter is omitted. This parameter may be specified only if the parameter `credentialInfo` is `true`. If the parameter `credentialInfo` is not `true` and this parameter is specified, its value will be ignored.

Authorization

The request must contain a bearer access token with the service scope. As a rule, obtaining this token via either an authorization code grant or client credentials grant OAuth 2.0 flow is possible. When the token is obtained through an OAuth 2.0 Authorization Code Grant, the user whose credentials list is requested is implicit in the token, so the userID request parameter should not be used.

The access token must be put in the Authorization header, as explained in RFC 6750. I.e., as follows:

Authorization: Bearer <token>

Response

Status-Line

If the request is successfully processed, the HTTP response contains the following Status-Line:

HTTP/1.1 200 OK

Content-Type Header

Content-Type: application/json;charset=UTF-8

Body

JSON object that contains the list of signature credentials of a user.

{
   "credentialIDs" : [{string}]
   "credentialInfos": : [{credentialInfo}]
}

Property

Type

Description

credentialIDs

String Array

Identifiers of the signature credentials of the user specified in the userID parameter of the request or associated with the access token included in the request.

credentialInfos

CredentialInfo Array

An array of the JSON objects, each one with the following structure:

{ 
   "credentialID": {string},
   <info_regarding_the_credentialID_credential>
}

where credentialID is the identifier of one of the credentials whose data is included in the list, and <info_regarding_the_credentialID_credential> refers to the information returned for this credential and consists of the same attributes as the JSON object returned by the Obtain a signature credential of a user operation.

Error Management

If the request does not contain the Authorization: Bearer header, the TRIDENT returns an HTTP response with the 401 Unauthorized Status Code.

If the request is not successfully processed, the TRIDENT returns an HTTP error response with the Content-Type: application/json;charset=utf-8 header and a JSON object in the body with the following properties:

error: Error code.
error_description: Additional description of the error. Not required.

Error Case	Status Code (HTTP)	error	error_description
The `userID` parameter was included in the request, and the request's access token is associated with the user (i.e., the access was authorized by a specific user).	400 Bad Request	`invalid_request`	`invalidUserId`
The `userID` parameter was not included in the request, and the request's access token is associated with the application. Or the `userID` parameter was included, but the user specified does not exist.	400 Bad Request	`invalid_request`	`invalidParameter`

Example

Request

The signature application requests the list of signature credentials of the user identified by john.doe@corporation.com. For this, it sends the following request to the TRIDENT and includes in it an access token with the service scope obtained in a Client Credentials Grant OAuth 2.0 authorization flow.

POST /trustedx-resources/csc/v2/credentials/list HTTP/1.1
Host: rse.corporation.com
Authorization: Bearer 9ade1210b7ac648b49defc577aa258eb2701b2064a14de13842524c2fd59c597
Content-Type: application/json
 
{
    "userID": "john.doe@corporation.com",
    "credentialInfo": true,
    "certificates": "single",
    "certInfo": true
}

Response

The TRIDENT responds to the signature application, providing it with the following information regarding signature credentials of the john.doe@corporation.com user.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
 
{
    "credentialIDs": ["m9jttphq6hpucr986si4hpc4e7", "g9iiilht5hwevt986si4hpc5y6"]
    "credentialInfos": [
        {
            "credentialID": "m9jttphq6hpucr986si4hpc4e7" 
            "description": "Corporative signature credential",
            "key": {
                "status": "enabled",
                "algo": [
                    "1.2.840.113549.1.1.13",
                    "1.2.840.113549.1.1.1",
                    "1.2.840.113549.1.1.11",
                    "1.2.840.113549.1.1.12"
                ],
                "len": 2048
            },
            "cert": {
                "certificates": ["MIIFpTCCBI2...m1SEW"],
                 "serialNumber": "67210661094051074244364068313147966416",
                 "validFrom": "20240116121230Z",
                 "validTo": "20250116121230Z",
                 "issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\", 
                             OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",
                "subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"
            },
            "authMode": "oauth2code",
            "multisign": 40,
            "lang": "en-US",
            "SCAL": "2"
         },
         {
            "credentialID": "g9iiilht5hwevt986si4hpc5y6" 
            "description": "Corporative signature credential",
            "key": {
                "status": "disabled",
                 "algo": [
                     "1.2.840.113549.1.1.13",
                     "1.2.840.113549.1.1.1",
                     "1.2.840.113549.1.1.11",
                     "1.2.840.113549.1.1.12"
                ],
                "len": 2048
            },
            "cert": {
                "certificates": ["MIIFpTCCBI2...n2TXk"],
                "serialNumber": "74376598109984627484011099193246767690",
                "validFrom": "20230116121230Z",
                "validTo": "20240116121230Z",
                "issuerDN": "CN=Entrust QA (SML) Class 3 Client CA - SHA256, OU=\"(c) 2015 Entrust, Inc. - for authorized use only\", 
                             OU=See www.entrust.net/legal-terms, O=\"Entrust, Inc.\", C=US",
                "subjectDN": "CN=John Doe, O=Corporation, L=Otwaw, ST=Ontario, C=CA"
            },
            "authMode": "oauth2code",
            "multisign": 40,
            "lang": "en-US",
            "SCAL": "2"
         }
}